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Organisation de la collection de problemes d'optimisation 
Modulopt dans l'environnement Libopt 
— Version 1.0 — 

Resume : Cette note decrit comment les problemes d'optimisation de la collection 
Modulopt sont organises dans l'environnement Libopt. Elle a pour but de servir de 
guide pour utiliser et enrichir cette collection dans cet environnement. 

Mots-cles : collection de problemes - environnement de test - evaluation de perfor- 
mance - Libopt - Modulopt - optimisation 
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1 The problems of the Modulopt collection 

In the Libopt terminology [3], a collection refers to a set of problems sharing some 
common features, such as their mathematical structure, coding language, audience, etc. 
In this note, we describe the installation of the Modulopt collection [5] in the Libopt 
environment. The features of the Modulopt problems, from the Libopt viewpoint, are 
the following: 

• they have an optimization nature and can be written in the form ([I]) below; 

• they can be smooth or nonsmooth; 

• they are written in Fortran 90/95; 

• they are issued from various application areas in scientific or industrial computing; 

• they can be freely distributed. 

The collection has a companion one, named "modulopttoys", which has the same 
features, except that the problems have an academic nature. In Libopt, these collections 
rub shoulders with the CUTEr collection [US]. 

The Modulopt collection contains nonlinear optimization problems coming from 
various application areas. The optimization problems are supposed to be written in 
the following form 



c E {x) = 0, 

where / : R n -» R, cj : R n -> R m/ , c E ■ M n -> R niE , l B , u B € R n , and h, m G R 



(K = KU {— co, +oo}). Actually B is the set of indices {1, . . . , n} and / is another set 
of indices with mj elements. We write I := (Ib,Ii) G K" x R m/ and u := (ub,uj) G 
R x R 1 . It is assumed that I < u, meaning that k < Ui, for all i G BUI. For making 
the notation compact, we note 

cb(x) := x, c(x) := (cb(x),cj(x),ce(x)), and m:=n + mj + mE- 

The Jacobian matrices of c/ and ce at x G R n are also denoted by 




(1) 



Ai{x) := c'j{x) and Ae{x) := c' E (x). 
We also introduce the nondifferentiable operator : R m — > 1 



R m defined by 



v 



# - 



max(0, Ib -v B ,v B - u B ) 
max(0, lj — vj,vj — uj) 
ve 




so that x is feasible for (P) if and only if c(x)* = 0. 

The Lagrangian of problem (P) is the function £ : R n x R ; 



m 



R defined at (x, A) by 



e(x,X) = f{x) + X l c{x). 
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Note that we take a single multiplier for two constraints present in the bound constraints 
h < Ci(x) < Ui, knowing that /j < m implies that at least one of the multipliers 
associated with Zj < and < Ui is zero. The optimality conditions at x read 
for some optimal multiplier A: 

' Vf(x) + c'{x) T X = 
c(x)# = 

< i e B U I , k < Ci(x) < m Xi = (3) 

i e BU I, k = Ci (x) => Xi < 

i E B U I, Ci(x) = m =^ Aj > 0. 

2 Running a Modulopt problem 

2.1 Notation and relevant directories 

We use the following typographic conventions. The typewriter font is used for a text 
that has to be typed literally and for the name of files and directories that exist as such 
(without making substitutions). In the same circumstances, a generic word, which has 
to be substituted by an actual word depending on the context, is written in italic 
typewriter font. 

Here are some directories of the Libopt hierarchy that will intervene continually in 
this note. Other important directories and files introduced in this note are listed in 
section [5j The main directories are 

• $LIB0PT_DIR 

is the environment variable that specifies the root directory of the Libopt 
hierarchy, 

• $LIBOPT_DIR/collections/modulopt 

is the root directory of the Modulopt collection in the Libopt environment, 

• $LIBOPT_DIR/collections/modulopt/probs 

is the directory that has a sub-directory for each of the problems of the Mo- 
dulopt collection installed in the Libopt environment, 

• $LIBOPT_DIR/solvers 

is the root directory of the solvers installed in the Libopt environment. 

2.2 The runopt script 

The simplest way of running a single Modulopt problem in the Libopt environment is 
by typing ('%' is the Unix/Linux prompt) 

7, echo "solv modulopt prob" | runopt, 

where, here and below, 

• solv stands for the name of a solver installed in the Libopt environment, one 
of those listed in 
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$LIBOPT_DIR/solvers/solvers . 1st; 

actually, the solver solv must have been prepared to run Modulopt problems, 
otherwise this command will not be understood by the Libopt environment; 
this subject is discussed in section UJ 

• prob stands for the name of a Modulopt problem currently available in the 
Libopt environment, one in the list 

$LIBOPT_DIR/collections/modulopt/all . 1st. 

By this command the optimization code solv is used to solve the Modulopt optimiza- 
tion problem prob. Of course solv has to be able to solve a problem with the features 
of prob (for example, a solver for unconstrained optimization problems is unable to 
solve problems with constraints). The code solv keeps in the file 

$LIBOPT_DIR/solvers/soWmodulopt/all . 1st 

the list of the Modulopt problems that it can structurally solve. 

See [3] or the manual page of runopt to learn how to run a group of problems with 
a given solver, using a single command line or a file describing what has to be done. 

The directory where the runopt script given above is typed is called the working 
directory. The Libopt scripts take care that this directory is not in the Libopt hierarchy. 
If this were the case, there would be a danger of incurable destruction. Indeed, a script 
like runopt generally removes several files from the working directory after a problem 
has been solved. 

2.3 The so Iwjiiodulopt script 

By decoding its standard input " solv modulopt prob", the runopt script above 
knows that it has to launch the following command: 

$LIBOPT_DIR/ solvers/ so Iv /modulopt/ so Iv _modulopt prob . 

In the standard distribution, so lw_modulopt is a Perl script, but nothing imposes that 
such a language be used. Such a script has to be written for each solver (actually for 
each solver-collection pair). Section U] explains how to do this. For the while, it is 
enough to know that it is decomposed in the following main steps. 

• The environment variables 

$M0DUL0PT_PR0B and $WORKING_DIR 

are respectively set to prob and to the working directory, so that these vari- 
ables can be used in the makefiles mentioned below. Actually, $WORKING_DIR 
is probably useless since all the Unix/Linux commands in the scripts or make- 
files are executed from the working directory (there is no change of directory 
made in them). 



RT n° 0123456789 



6 



J. Ch. Gilbert 



• Then the target prob of the following makefile is executed 

$LIBOPT_DIR/collections/modulopt/probs/prob/Makef ile. 

The aim of this target is to make symbolic links in the working directory to 
the source and data files in the prob directory 

$LIBOPT_DIR/ collections/modulopt/probs/prob, 

to produce an archive named prob . a in the working directory, which contains 
the problem object files allowing the execution of the problem, and finally to 
remove the now useless symbolic links from the working directory. 

• Next, the Perl script executes the target so Zf_modulopt_main of the following 
makefile 

$LIBOPT_DIR/solvers/soWmodulopt /Makefile. 

Its aim is to make a symbolic link in the working directory to the source file 

$LIBOPT_DIR/ solvers/ so l-u/modulopt/ so Iv _modulopt_main. f 90 

of the main program, to compile it and link it with the archive prob. a. of 
the Modulopt problem previously generated. This produces the executable 
file so Lf_modulopt_main in the working directory. Then the target removes 
from the working directory the now useless symbolic link so Iv _modulopt_ 
main. f 90 and file so l-ujnoduloptjnain.o. 

• The program 

so l^_modulopt_main 

is then executed in the working directory. This one solves the problem prob 
with the solver solv. 

• Some cleaning is then done in the working directory: so i-y _modulopt_main is 
removed (probably with other files, depending on the solver) and the target 
prob _clean of the following makefile is executed: 

$LIBOPT_DIR/collections/modulopt/probs/prob/Makef ile 

Its aim is to remove from the working directory, the files related to the problem 
just solved, typically the archive prob. a and the prob data files. 

3 Introducing a new problem in the Modulopt collection 

3.1 Overview 

Suppose that we want to introduce a new problem in the Modulopt collection and that 
this one is called 
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prob . 

The description of the runopt script above shows that, one has to proceed as follows. 

• Insert the name prob in the list of Modulopt problems 

$LIBDPT_DIR/collections/modulopt/all . 1st 

(and possibly in other lists in the same directory, such as the one related to 
unconstrained problems unc.lst, quadratic problems quad. 1st, etc, as well 
as the list of typical problems of the Modulopt collection default. 1st, if 
this is appropriate). This is an ascii file. An alpha-numeric order has been 
adopted, but this feature is not taken into account by the Libopt scripts. 
Comments are possible; they start from the character '#' up to the end of 
the line. 

• If a solver called solv is able to solve a problem like prob, it may be appro- 
priate to insert the name prob in one or more files among 

$LIBOPT_DIR/solvers/soZ-u /modulopt/* .1st. 

This assumes that the directory $LIBOPT_DIR/solvers/so lw /modulopt ex- 
ists and that the solver has been prepared to solve problems from the Modu- 
lopt collection (see section H] to know how to do this). 

• Create the directory 

$LIBOPT_DIR/ collections/modulopt/probs/prob, 

and put in that directory, all the files that define the problem prob: source 
files, header files (if appropriate), and data files (if appropriate). This is 
further described in section 13.21 below. 

• Create the makefile 

$LIBOPT_DIR/collections/modulopt/probs/prob/Makef ile, 
with the following two targets: 

o prob, which specifies how to obtain in the working directory an archive 
with all the object files defining prob and which makes symbolic links in 
the working directory to the data files required to solve the problem; 

o prob _clean, which specifies which files has to be removed from the working 
directory after having solved prob. 

This is further discussed in section 13.31 below. 
3.2 The subroutines denning a Modulopt problem 

In principle, the problem can be described in any compiled language, provided the 
binary files can be gathered into an archive. Below, we assume that the problem is 
written in Fortran 95. 
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The problem-independent makefile 

$LIBOPT_DIR/solvers/soZu/modulopt /Makefile 

assumes that the problem to execute is in the archive prob.a. in the working direc- 
tory. On the other hand, the problem-independent main program so lt/_modulopt_ 
main assumes that the archive prob.a contains seven subroutines: dimopt, initopt, 
simulopt, postopt, inprodopt, ctonbopt, and ctcabopt, which are described below. 

In the description of the subroutine arguments, an argument tagged with (I) means 
that it is an input variable, which has to be initialized before calling the subroutine; 
an argument tagged with (O) means that it is an output variable, which only has a 
meaning on return from the subroutine; and an argument tagged with (10) is an input- 
output argument, which has to be initialized and which has a meaning after the call 
to the subroutine. Arguments of the type (O) and (10) are generally modified by the 
subroutine and therefore should not be Fortran constants] 

The subroutine dimopt 

The subroutine dimopt is called by the main program so Iv _modulopt_main to get the 
dimensions of the problem. In Fortran 95, it has the following calling structure: 

subroutine dimopt (n, mi, me, nizs, nrzs, ndzs) 

n (O): positive integer variable. This is the number n of variables to optimize in the 
problem, those denoted x = (x±, . . . , x n ) in (P). 

mi (O): nonnegative integer variable. This is the number mi of nonlinear inequal- 
ity constraints, of the form Zj < Ci(x) < m (i = l,...,mj), for some nonlinear 
functions a : R n -> R. 

me (O): nonnegative integer variable. This is the number rriE of nonlinear equality 
constraints, of the form Ci(x) = (i = 1, . . . , UIe), for some nonlinear functions 
d : R n -» R. 

nizs (O), nrzs (O), ndzs (O): positive integer variables. These are the dimensions 
of the variables izs, rzs, and dzs (respectively), which are integer, real, and 
double precision working zones for the Modulopt problem. The solvers must 
not affect their content. The main program so l^_modulopt_main associated with 
the solver solv must allocate memory for the variables izs, rzs, and dzs just 
after having called dimopt, see section HI point 4.1 on page 1171 This implies that 
using Fortran 77 is not an appropriate language for writing the main program 
so Zw_modulopt_main. Note that the value of nizs, nrzs, and ndzs can be zero. 

The subroutine initopt 

The subroutine initopt is called to initialize the problem. In Fortran 95, it has the 
following calling structure: 
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subroutine initopt (pname, n, mi, me, x, lx, ux, dxmin, li, ui, 

dcimin, inf , tolopt, simcap, info, izs, 
rzs, dzs) 

pname (O): character string of length 132, giving the name of the problem, 
n (I), mi (I), me (I): dimensions of the problem. Their meaning is given in the descrip- 
tion of dimopt. 

x (O): double precision array of dimension n, providing a starting point for the 
optimization solver. 

lx (O), ux (O): double precision array of dimension n, providing the bounds on 
the variable x. In other words, Xi is required to satisfy lx(i) < x.; < ux(z), 
for % = 1, ...,n. The lower (resp. upper) bound lx(0 (resp. ux(i)) is set to 
-inf (resp. inf) is the bound does not exist; see below for the meaning of inf. 
Therefore, the arrays lx and ux must have been declared in the calling program 
with dimension n, even if a solver not dealing with bound constraints is intended 
to be used. 

dxmin (O): double precision variable, providing the resolution in x for the Zoo norm: 
two points whose distance in M. n for the sup-norm is less than dxmin can be con- 
sidered as indistinguishable. This data can be used in line-search or trust-region. 
It is also useful to detect bounds that are active up to that precision. 

li (O), ui (O): double precision array of dimension mi := mi, providing the bounds 
on the constraint values c/(x). In other words, Cj(x) is required to satisfy li(i) < 
Ci(x) < ui (i) , for i = 1, . . . , mj. 

dcimin (O): double precision variable, providing the resolution in cj for the 

norm: two inequality constraint values whose distance in M. mi for the sup-norm is 
less than dcimin can be considered as indistinguishable. This data can be useful 
to detect inequality constraints that are active up to that precision. 

inf (O): double precision variable, specifying what is the infinite value for the 
bounds on x and cj(x). In other words, when lx(z) < —inf (resp. li(i) < —inf), 
there is no lower bound on xi (resp. q(x)). A similar convention is adopted for 
the upper bounds. 

tolopt (O): double precision array of dimension 4, providing the tolerances on op- 
timality that a pair (x, A) must satisfied in order to be considered as a solution to 
the problem. More specifically, the pair (x,A) can be considered as a satisfiable 
KKT point if 




RT n° 0123456789 



10 



J. Ch. Gilbert 



where sgn 3 ,(A) € K m is defined as follows 



(sgn x (A))i 



= < 




if i € B U / and Xj ^ [Z* + tolopt (2) , +oo[ 

if i 6 5 U / and Xi G [Zj + tolopt (2) , m - tolopt (2)] 

if i £ B U / and Xj ^ ] — oo, tij — tolopt (2)] 



if i € £. 



The tolerance tolopt (4) is aimed at being used by minimization software for 
nonsmooth functions and provides a tolerance of the duality gap. This way of 
checking optimality will probably be improved in a future version of the collection, 
in the light of [2]. 

simcap (O): integer array of dimension 4. It specifies the simulator capabilities. A 
negative values means that the related function is not present or that the capability 
is not considered by the simulator. 

simcap (1) < the simulator cannot evaluate the cost-function /; it may be as- 
sumed then that this one is constant (or zero), so that the problem 
is a feasibility one; 
= the simulator can evaluate the cost- function /; 
= 1 the cost-function / is nonsmooth (this is the only place where this 
property of the problem can be detected) and the simulator can 
evaluate / and a subgradient g; 
= 2 the simulator can evaluate the cost-function / and its gradient g; 
simcap (2) < the simulator cannot evaluate the inequality constraint function 
cj; this is normally because there is no inequality constraints; 
= the simulator can evaluate c/; 
= 1 the simulator can evaluate c/ and its Jacobian c^-; 
simcap (3) < the simulator cannot evaluate the equality constraint function ce', 
this is normally because there is no equality constraints; 
= the simulator can evaluate ce\ 
= 1 the simulator can evaluate ce and its Jacobian c' E ; 
simcap (4) < the simulator cannot evaluate Hv , the product of the Hessian of 
the Lagrangian H := V^. x £(x, A) times a vector v; 
= 1 the simulator can evaluate a product Hv; 
= 2 the simulator can evaluate the H. 
info (O): integer variable. If negative (< 0), so Iv _modulopt_main should consider 

that the initialization of the problem by initopt has failed and should stop, 
izs, rzs, dzs (O): integer, real, and double precision arrays that initopt should 
initialize. These variables are made available to the Modulopt problem. Their 
dimensions have been provided on return from dimopt and they should have been 
allocated by the main program so Z-y _modulopt_main associated with some code 
solv. 
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The subroutine simulopt 

The subroutine simulopt is the simulator of the problem. It can be called by solv_ 
moduloptjnain, before calling solv. It is also called by the latter to have information 
(function and their derivatives) on the problem to solve. In Fortran 95, it has the 
following calling structure: 

subroutine simulopt (indie, n, mi, me, x, lm, f , ci, ce, g, ai, 

ae, v, hlv, hi, izs, rzs, dzs) 

indie (10): integer variable monitoring the communication between the solver and 
the simulator. The simulator simulopt recognizes the following values of indie. 

= 1: The simulator can do anything except changing the value of the arguments 
of simulopt. Typically it prints some information on the screen, in a file, or 
on a plotter. Some solver calls the simulator with this value of indie at each 
iteration. 

= 2: The simulator is asked to compute the value of the functions f = f(x) € M. 

(cost function), ci = cj(x) E W ni (inequality constraints), and ce = ce(x) € 

M ms (equality constraints) at a given point x. 
= 3: The simulator is asked to compute g = V/(x) 6 M n (gradient of / at x for 

the Euclidean scalar product), ai = c'r(x) (mj x n Jacobian matrix of c/ at x, 

hence the entry of ai must be the partial derivative dci/dxj evaluated 

at x), and ae = c' E (x) (tjie x n Jacobian matrix of ce at x). 
= 4: The simulator is asked to compute f = f(x), ci = c/(x), and ce = ce(x) at 

a given point x, as well as the gradient g = Vf(x) 6 R n , ai = c'j(x), and 

ae = c' E (x). 

= 5: The simulator is asked to prepare for subsequent computations of products 
Hv, where H := V xx i{x, A) is the Hessian of the Lagrangian at (x, A) (see 
([2])) and v will be an arbitrary vector (see indie = 6 below). In some 
cases, it is convenient to compute the full Hessian of the Lagrangian H when 
indie = 5. In other cases, computing H is too expensive and nothing has to 
be done when simul is called with indie = 5. 

= 6: The simulator is asked to compute a product Hv, where H := V xx l(x,X) is 
the Hessian of the Lagrangian at the point {x, A) and v £ W 1 is an arbitrary 
vector. Note that it is not necessary to evaluate the whole matrix H to 
compute a product Hv; indeed, Hv is also the directional derivative of the 
gradient of the Lagrangian in the direction v: 



= 7: The simulator is asked to compute the Hessian of the Lagrangian H := 

V xx £(x,X) at the point (x,A). 
On the other hand, the simulator simulopt can also send a message to the solver, 
by giving to indie one of the following values. 



RT n° 0123456789 




12 



J. Ch. Gilbert 



> 0: normal call; the required computation has been done. 
= — 1: by this value, the simulator tells the solver that it is impossible or undesir- 
able to do the calculation at the point x given by the solver. The reaction 
of the solver will vary from one solver to the other. 
= —2: the simulator asks the solver to stop, for example because some events that 
the solver cannot understand (not in the field of optimization) has occurred, 
n (I), mi (I), me (I): dimensions of the problem. Their meaning is given in the descrip- 
tion of dimopt. 

x (I): double precision array of dimension n, providing the point at which the sim- 
ulator has to evaluate functions and derivatives. 

lm (I): double precision array of dimension m, providing the current value of the 
dual variable A. This one determines, with x, the primal-dual variables at which 
the simulator has to evaluate the Hessian of the Lagrangian or the product of this 
Hessian with a vector (this depends on the value of indie). 

f (O): double precision variable, providing the cost function value f{x) if indie = 2 
or 4 on entry. 

ci (O): double precision array of dimension mj, providing the inequality constraint 

value ci(x) if indie = 2 or 4 on entry, 
ce (O): double precision array of dimension tue, providing the equality constraint 

value ce(x) if indie = 2 or 4 on entry, 
g (O): double precision array of dimension n, providing the gradient of the cost 

function V/(a?) if indie = 3 or 4 on entry, 
ai (O): double precision array of dimension mj x n, providing the Jacobian matrix 

of the inequality constraint function c'j(x) if indie = 3 or 4 on entry, 
ae (O): double precision array of dimension mj x n, providing the Jacobian matrix 

of the equality constraint function c' E (x) if indie = 3 or 4 on entry, 
v (I): double precision array of dimension n, providing the vector v that multiplies 

the Hessian of the Lagrangian if indie = 6 on entry, 
hlv (O): double precision array of dimension n, providing the product Hv of the 

Hessian of the Lagrangian H with a vector v if indie = 6 on entry, 
hi (O): double precision array of dimension (n,n), providing the Hessian of the 

Lagrangian H if indie = 7 on entry, 
izs, rzs, dzs (10): integer, real, and double precision arrays that simulopt can 

use and modify. These variables are made available to the Modulopt problem. 

Their dimensions have been provided on return from dimopt and they should have 

been allocated by the main program so Iv _modulopt_main associated with some 

code solv. 

The subroutine postopt 

The subroutine postopt is normally called by the main program so Iv _modulopt_main 
to allow the problem to provide a post-optimal analysis. Some problems will take 
advantage of this opportunity, but most of them won't (they will provide a subroutine 



INRIA 



Organization of Modulopt in Libopt 



13 



with en empty body). The most trivial operation that can be done in this subroutine 
is to print the solution on the screen. Another possibility is to check second order 
optimality. The flexibility offered by this subroutine will allow the user of libopt to 
make other job than comparing the effect of using various solvers on his/her problem. 
In Fortran 95, postopt has the following calling structure: 

subroutine postopt (n, mi, me, x, lm, f , ci, ce, g, ai, ae, hi, 

izs, rzs, dzs) 

n (I), mi (I), me (I): dimensions of the problem. Their meaning is given in the descrip- 
tion of dimopt. 

x (10), lm (10): double precision arrays of dimension n and m respectively. They 
provide the primal (x = x) and dual (lm = A) variables determined by the solver. 
They may be modified, since libopt will no longer use them. 

f (10), ci (10), ce (10), g (10), ai (10), ae (10), hi (10): variables providing the value 
of f(x), ci(x), ce(x), g(x), Aj(x), Ae(x), and S/ xx £(x,X) found by the last call 
to simulopt (hence the actual values depend on the capabilities of the simulator 
and the design of the solver). See the description of simulopt for the type and 
dimension of these variables. These may be modified, since libopt will no longer 
use them. 

izs, rzs, dzs (10): integer, real, and double precision arrays that postopt can 
use and modify. These variables are made available to the Modulopt problem. 
Their dimensions have been provided on return from dimopt and they should have 
been allocated by the main program so Ziy_modulopt_main associated with some 
code solv. 

The subroutines inprodopt, ctonbopt, and ctcabopt 

Some unconstrained optimization solvers can deal with gradients that are associated 
with an inner product, say (x,y) t— > (x,y), different from the Euclidean inner product 
(x, y) h-> x T y. Such an inner product is a way of rescaling the problem. These solvers 
must be informed of this inner product and this is the role of the subroutine inprodopt. 
We describe the structure of the subroutine in Fortran 95. 

subroutine inprodopt (n, vl , v2, ip, izs, rzs, dzs) 

n (I): dimension of the vectors whose inner product is going to be taken. 

vl (I), v2 (I): double precision arrays of dimension n. These are the vectors whose 

inner product is desired, 
ip (O): double precision variable representing the inner product of vl and v2. 
izs, rzs, dzs (10): integer, real, and double precision arrays that postopt can 

use and modify. These variables are made available to the Modulopt problem. 

Their dimensions have been provided on return from dimopt and they should have 

been allocated by the main program so li/_modulopt_main associated with some 

code solv. 
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Some unconstrained optimization solvers not only need the inner product subroutine 
inprodopt but also subroutines that make a change of coordinates from the canonical 
orthogonal basis of W 1 to some orthogonal basis for the inner product (•,•). The canon- 
ical orthogonal basis of M. n is the set of vectors {e*}™ =1 , where the jth component of 
e l is equal to <5y (the Kronecker symbol, which is one when i = j and zero otherwise). 
If a vector is written Y2i m t ne canonical basis and Yli y« e * m the considered or- 
thogonal basis, the subroutine ctonbopt gives the coordinates y := (yi, ■ ■ ■ ,y n ) from 
x := (x±, . . . ,x n ) and the subroutine ctcabopt gives the coordinates x from y. 

For example, suppose that 

{u,v) = u T M T Mv, 

where M is a nonsingular n x n matrix, such that a linear system with the matrix M 
is easy to solve (for example M could be triangular). One can take e* = M~ l e\ for 
1 < i < n, since then (e l ,e^) = (e ! ) T M T Me^ = [e % ^e? = 5ij. Knowing the coordinates 
x := (x\, . . . , x n ) of a vector in the canonical basis, its coordinates y := (yi, . . . , y n ) in 
the basis {e*}" =1 can be computed by 

Vj = =Y f x i (ff,M- 1 &) = ^^(e l ) T M T ^ = (Mx)j. 

i i i 

We have shown that y = Mx. In that example, the subroutine ctonbopt will compute 
y = Mx knowing x, while the subroutine ctcabopt will compute x = M _1 y knowing y. 

Here is the description of the subroutines ctonbopt and ctcabopt in Fortran 95. 
The variables x = x and y = y have the same meaning as in the discussion above. The 
parameters izs, rzs, and dzs have the same meaning as in the subropuitine inprodopt. 



subroutine 


ctonbopt 


(n, x, y, izs, rzs, 


dzs) 




subroutine 


ctcabopt 


(n, y, x, izs, rzs, 


dzs) 



Of course, if the inner product implemented in inprodopt is the Euclidean inner prod- 
uct, ctonbopt will just copy y into x, while ctcabopt will just copy x into y. 

3.3 The makefile describing how to run the Modulopt problems 

In the framework introduced in section [3TTT the target prob of the makefile 

$LIBOPT_DIR/collections/modulopt/probs/prob /Makefile 

has to specify how to get in the working directory the archive prob. a containing the 
code of dimopt, initopt, simulopt, postopt, inprodopt, ctonbopt, and ctcabopt. 
It must also create in the working directory symbolic links to the data files (if any) 
useful for the execution of the problem. Note that this makefile is launched from the 
working directory, so that ' . ' in the makefile refers to that directory. 
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The target prob_clean of the same makefile, should also clean up the working 
directory from the files related to the problem just solved. This makefile is also launched 
from the working directory. 

One must keep in mind that the makefile must be organized in such a way that 
no file is generated in the problem directory $LIBOPT_DIR/collections/modulopt/ 
probs/ prob. Only the working directory can be modified, so that several users can use 
the Libopt environment at the same time. 

4 Making a solver able to solve Modulopt problems 

In this section, we consider the case when it is desirable to make a solver of optimiza- 
tion problems, installed in the Libopt environment, able to solve problems from the 
Modulopt collection. Let 

solv 

be the name of the considered solver. If the solver does not already exist in the Libopt 
environment, the name solv has to be added to the file 

$LIBOPT_DIR/solvers/solvers . 1st, 

which contains the list of solvers of the Libopt environment, and the following directo- 
ries must be created 

$LIBOPT_DIR/solvers/solv 
$LIBOPT_DIR/solvers/soWbin, 

as well as an empty file 

$LIBOPT_DIR/solvers/soWcollections.lst, 

which contains the list of collections that the solver solv can consider (none if this is 
the first time solv is introduced in the Libopt environment). 

We now give the next steps to follow, together with some explanations. 

1. Create the directory 

$LIBOPT_DIR/solvers/soi-y /modulopt, 

which will contain the programs/scripts to run solv on the Modulopt problems, 
and add the name modulopt to the list 

$LIBOPT_DIR/solvers/soZ-y /collections .1st, 

which indicates that solv can deal with the Modulopt collection. 

2. Create the files 

$LIBOPT_DIR/solvers/so Iv /modulopt/all . 1st 
$LIBOPT_DIR/solvers/soZv/modulopt/def ault .1st. 
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• The first file (all . 1st) must list the problems from the Modulopt collection that 
solv is able to solve or, more precisely, those for which it has been conceived. It 
can contain comments, which start with the '#' character and go up to the end of 
the line. The easiest way of doing this is to start with a copy of the file 

$LIBOPT_DIR/collections/modulopt/all . 1st, 

which lists all the Modulopt problems, and to remove from the copied file those 
problems that do not have the structure expected by solv. For example, if solv 
is a solver of unconstrained optimization problems, remove from the copied file 
all. 1st, all the problems with constraints. The features of the Modulopt prob- 
lems are given in the files 

$LIBOPT_DIR/collections/modulopt/all . 1st, 
$LIBOPT_DIR/collections/modulopt/probs/PROBLEMS. 

Note that other lists exist in the directory $LIBOPTJ)IR/collections/modulopt, 
which might be more appropriate to start with than the list all. 1st. 

• The second file above (default . 1st) can contain any subset of the problems listed 
in the first file (all. 1st). This file is used as the default subcollection when no 
list is specified in the runopt script. Therefore, it is often a symbolic link to the 
first file all. 1st, obtained using the Unix/Linux command 

In -s all. 1st default. 1st 

in the directory $LIBDPT_DIR/collections/modulopt. 

3. Create the executable file 

$LIBOPT_DIR/solvers/soZi//modulopt/soZi'_modulopt. 

This is the script launched by runopt to run solv on a single Modulopt prob- 
lem. More precisely, this script takes care of the tasks that can be described using 
Unix/Linux commands, such as making symbolic links, executing makefiles, remov- 
ing files, etc. This is not an easy program to write from scratch (see [3]) but adapting 
a script used by another solver is rather straightforward. For example, one can copy, 
rename, and modify the Perl script 

$LIBOPT_DIR/ solvers/ sqppro/modulopt/sqpprojnodulopt. 

The only changes to make in the copied and renamed script (hence now called 
so L^_modulopt) consists in substituting the two occurrences of the solver name 
sqppro by solv (one in a comment, another in the definition of the variable $solv- 
name). That's all! 

4. Create the main program 

$LIBOPT_DIR/ solvers/ so Iv /modulopt/ soZf_modulopt_main. f 90. 

This program is very solver dependent and is, with the next step to which it is linked, 
the most difficult task to realize. It is the main program that will be linked with 
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the subroutines describing the problem from the Modulopt collection selected by the 
runopt script, those in the archive prob. a (if the selected problem is prob ) created 
by the makefile $LIBOPT_DIR/collections/modulopt/probs/prob/Makef ile (see 
section 13. 3p . The language used to write this main program is arbitrary, provided it 
(or its object form generated by some compilor) can be linked with the object files 
issued from the compilation of the Fortran files describing the Modulopt problems 
(dimopt, initopt, simulopt, postopt, inprodopt, ctonbopt, and ctcabopt). 

If Fortran 90/95 is the adopted language, the easiest way to proceed is to copy and 
rename the file 

$LIBOPT_DIR/solvers/sqppro/modulopt/sqppro_modulopt_main. f 90 

into the file 

$LIB0PT_DIR/ solvers/ so Iv /modulopt/ so Z^_modulopt_main. f 90. 

Since this main program is very solver dependent, its part dealing with the solver 
will have to be thoroughly modified. Let us describe the structure of the program. 

4.1. After the declaration of variables, the program calls the subroutine dimopt 
to get the dimensions of the Modulopt problem that will be selected by the 
runopt script. These dimensions are then used to allocate dimension dependent 
variables, including izs, rzs, and dzs. 

4.2. The problem data are then obtained by calling the subroutine initopt. This 
is the good spot to verify that the features of the problem are compatible with 
the solver capabilities, using the variable simcap. 

4.3. Some optimization solver requires that the simulator be called before launching 
the optimization. In this case, this is the good spot for doing so, by calling 
simulopt. 

4.4. Next, the program calls the optimization solver solv, after having initialized 
its arguments and opened relevant files. 

4.5. Once the optimization has been completed, it is important to write the libopt 
line, which summarizes the performance of the solver solv on the currently 
solved Modulopt problem. See [3] or the libopt man page. 

4.6. It is nice to let the problem do its post-optimal analysis (if any) by finally 
calling postopt. 

Note that a particular solver usually requires a simulator with another structure than 
the one of simulopt. Therefore an interface between simulopt and the simulator 
required by solv should be written and placed in the file so Iv _modulopt_main. f 90. 

5. Create the makefile 

$LIBOPT_DIR/solvers/soZ-u /modulopt /Makefile. 
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The aim of this makefile is to tell the Libopt environment how to link the solver 
binary with the object files describing the Modulopt problem selected by the runopt 
script. If the latter is prob, the corresponding object files will be at link time in the 
working directory in the archive prob. a (see section . The easiest way of doing 
this is to start with an existing makefile, like 

$LIBOPT_DIR/solvers/sqppro/modulopt /Makefile. 
This one will be copied and renamed into the file 

$LIBOPT_DIR/solvers/soli/ /modulopt /Makefile 

and then modified. 

You can now try the command 

echo "solv modulopt prob" | runopt -v 

where the flag -v (verbose) is used to get detailed comments from the Libopt scripts, 
which then tell what they actually do. The flag -t (test mode) can be used instead, if 
you want to see what the scripts would do without asking them to do it. 

5 Directories and files 

In this section, we list some important directories and files encountered in this note. 
Recall that $LIBOPT_DIR is the environment variable that specifies the root directory 
of the Libopt hierarchy. Below, solv is the generic name of a particular solver known 
to the Libopt environment. 

• $LIBOPT_DIR/collections: 

directory of the collections of problems the Libopt environment can deal with. 

• $LIBOPT_DIR/collections/collections . 1st: 

list of collections known to and installed into Libopt. 

• $LIBOPT_DIR/collections/modulopt: 

root directory of the Modulopt collection in the Libopt environment. 

• $LIBOPT_DIR/collections/modulopt/all . 1st: 
list of all the problems of the Modulopt collection. 

• $LIBDPT_DIR/collections/modulopt/probs: 

directory containing one sub-directory for each problem of the Modulopt collection. 

• $LIBOPT_DIR/solvers: 

root directory of the solvers the Libopt environment can deal with. 

• $LIBOPT_DIR/solvers/solvers . 1st: 

list of solvers known to and installed into Libopt. 

• $LIBOPTJ)IR/solvers/so Wcollections.lst: 

list of collections the code solv has been prepared to deal with. 
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• $LIBDPT_DIR/solvers/soi-y /modulopt: 

directory containing the scripts and programs specifying how to run the code solv 
on problems from the Modulopt collection. 

• $LIBOPT_DIR/solvers/so Wmodulopt/all.lst: 

list of problems from the Modulopt collection, for which the solver solv is designed. 

• $LIBOPT_DIR/solvers/ so liz/modulopt/ so l^_modulopt: 

Perl script specifying the Unix/Linux commands useful to run the solver solv on 
a single problem of the Modulopt collection. 

• $LIBOPT_DIR/solvers/soZ , y /modulopt/ so Iv _modulopt_main. f 90: 

Fortran 90/95 main program that is used to run solv on a Modulopt problem 
selected by a runopt script, say prob. This program is linked with the object files 
(gathered in the archive prob. a. in the working directory) describing prob. 
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